Developer CD Series 1996 May: Tool Chest

home *** CD-ROM | disk | FTP | other *** search

/ Developer CD Series 1996 May: Tool Chest / Developer CD Series May 1996 (Tool Chest) (Apple Computer) (1996).iso / Tool Chest / Development Tools & Languages / Dylan Related / Dylan Interim Manual / errata 16-Mar-95 next >

Wrap

Text File | 1995-03-16 | 22.2 KB | 664 lines | [TEXT/ttxt]

DYLAN INTERIM REFERENCE MANUAL ERRATA updated 3/16/95 ===================================== This is a list of known errors and omissions in the June 1994 Dylan Interim Reference Manual (DIRM). Many of the items in the errata sheet are specific corrections, but some of the items are questions that point to places where we know the DIRM is inconsistent or unclear. These questions will be resolved in the new Dylan language reference, which will be published in 1995. In the interim, we hope that this errata sheet will be helpful to people who want to learn about Dylan or who are using an early Dylan implementation. MISSING or PARTIALLY INCORPORATED --------------------------------- The classes <object>, <collection>, and <pair> don't have explicit definitions anywhere. The manual notation of double arrow for "evaluates to" or "returns value" is not explained anywhere. Missing or partially incorporated language design decisions: - Parameterized Types (The interim book includes the general material, such as <type> and subtype?, and the part about ambiguous methods signaling an error. The limited and union types are not incorporated.) - Evaluation of Top Level Forms - Collection allocation (Rob MacLachlan, Feb 18th) - Macro specification (Apple, 6/17) - Keyword default syntax (Keith Playford, May 18th) - Allow IEEE Float Comparisons V3 - Accessor Method Signatures V4 - Implicit GF Parameter Lists V4 - Optional-body-intermediate (Moon, June 24th) - expressions in detail-list (Moon, June 24th) - "Not Identical" operator (Keith Playford) - Keyword parameter types V6 (Gwydion Group, 9/7) - Block Dynamic Extent V3 (Rob MacLachlan, 9/22) - No More Than One Cleanup (Rob MacLachlan, 9/12) - Unreserved Define Words V4 (Keith Playford, 9/28) - Defining-macro syntax (Keith Playford, 9/6) - Free References in Macros (Apple, 9/16) - Template Hygiene Violation (Moon, 9/11) - Apple Extensions Grammar V3 (Moon, 9/29) - ?name:constraint instead of ?constraint:name (Macro Issue 5) - ?expression instead of ?expr (Macro Issue 6) - Add CL "multiple-value-prog1" functionality V4 (Tim McNerney, 9/27) - Unreserved Intermediate Words V3 (Moon, 9/30) Important note: --------------- Most of the proposals referenced above are new decisions since the release of the DIRM, and have not been written up for release to the public. They are listed here for completeness. Many of them are related to the macro system which was recently added to the language, but which has not yet been written up for public distribution. The above missing or partially incorporated proposals have not been entirely incorporated into the errata sheet. For example, some of the corrections to Appendix B may be superseded by the recently accepted macro proposals. GENERAL COMMENTS ---------------- Categories of classes (such as [Abstract Class], [Instantiable Class], and [Sealed Class]) should be reviewed. Many of them are wrong or incomplete. Likewise for functions/GFs/methods (although this is not so bad as the classes now). Lots of terminology is inconsistent. For example: execute/evaluate statement/expression/form Error reporting should be reviewed and made consistent. Sometimes a situation "is an error," sometimes "an error is signaled," sometimes "an implementation may choose to signal an error," etc. The book is not always clear about what environment things are evaluated in. This should be checked and clarified where it is ambiguous. In definitions, parameter names such as "integer1" (used to indicate specializers) and metasyntactic words like "implicit-body" should be reviewed for correctness. Perhaps we should come up with new conventions that make the specializers of parameters more explicit. SPECIFIC COMMENTS ----------------- p.xvii [Acknowledgements] Tim McNerney's name was incorrectly spelled. p.8 [lexical notation] What is the legal Dylan character set? On comments that whitespace is ignored: this is not true with regard to strings, character constants, literals, or // comments. The specification of comments is incomplete. Must comments be separated by whitespace from the preceding identifier? is foo//bar an eight character symbol or a three character one followed by a comment? Are \-escapes inside #"..." symbols interpreted the same way as \-escapes inside strings? Yes. The accepted \-escapes in strings should be listed here. They are: \a bell ("alarm") \b backspace \e escape \f formfeed \n newline \r return \t tab \0 null This section doesn't incorporate the decision that two consecutive literal strings count as one string. pp.9-10 [getters and setters] The relationship between foo, foo-setter, and foo := bar isn't explained well. Clarify that the -setter suffix is simply a convention, but := depends on it. p.11 [define variable examples] define variable is shown returning a value. (or at least, printing the name of the variable defined.) This is inconsistent with other examples. p.14 [statement bodies] The description doesn't explain that if there are zero expressions, an implicit body returns #f. pp.15-16 [operator escape character] We need to figure out whether + (for example) calls \+ in the current scope or \+ in the Dylan module. pp.16, 25 [special syntax for element/aref] We need to figure out whether [...] calls element in the current scope or element in the Dylan module. p.16 [slot reference syntax] What is the precedence of . ? It binds tighter than any binary operator. Is whitespace allowed around . ? Yes, but the stylistic convention is not to use whitespace. p.17 [Syntax of Dylan Files] Since module: is required, the header must consist of one or more key-value pairs (not zero or more). p.18 [standard header keywords] The language: keyword was removed in Design Note 33. It should be restored. Can the header keywords author:, copyright:, and version: appear more than once? p.19-22 [define variable] The syntax of variable bindings should specify commas between the variables. This does not say whether an unspecified type clause is equivalent to ":: <object>." When binding multiple values, may the same variable name appear more than once in the bindings list? if so, what does this mean? p. 20, 47, 156 [local declaration values] The DIRM fails to say what the following definition would return if it executed: define method foo () bar(); let x = baz(); end method; The answer is that local declarations presume implicit body semantics. The "body" is empty and, therefore, returns #f. p.24 [examples] define variable is shown returning a value. (or at least, printing the name of the variable defined.) This is inconsistent with other examples. p.24, 25 [:= insufficiently defined] The description of := should say that the new-value expression is evaluated before the place expression. This makes using := consistent with calling -setter functions directly. p.25 [extended form] "The evaluation time of the variable element-setter, which this expression is defined to invoke, is unspecified": should also mention aref-setter. p.27 [definition of ~] "=> boolean" is misleading, since there is no <boolean> class. In fact, any value could be returned! p. 29, 30 [case and select optional semicolon] As described, a semicolon is required after body_n even if no otherwise clause appears. Reasoning that the semicolon is used as a separator rather than terminator, it should be removed here. Checking the grammar in the interim report also seems to indicate that semicolon is used as a separator between constituents_opt in a case-body. Thus, case should look something like this: case test_1 => body_1 ; ... test_n => body_n [ ; otherwise => otherwise-body ] [;] end [case] and select should read as follows: select ( target-form [ by test ] ) match_1a , ... match_1n => body_1; ... match_ma , ... match_mn => body_m [ ; otherwise => otherwise-body ] [;] end [select] p. 30 [select conflicting statements] The sentence "each match is evaluated to produce a match object" erroneously implies that all matches are evaluated before the match objects are compared with the test. The sentence should be replaced by "the match is evaluated to produce a match object." p.31 [| and &] Is \| (form1, form2) equivalent to form1 | form2? Is \& (form1, form2) equivalent to form1 & form2? p.32 [for] for is a macro, not a special form. "for allows one or more clauses" is not completely correct. commas are not shown where they're needed in for syntax. p.33 [numeric clauses in for] Clarify that the increment defaults to 1 regardless of the type of the variable. p.33 [collection clauses in for] When is forward-iteration-protocol(collection) evaluated? In general, all the collection clause steps should make clear exactly when and which functions from the iteration protocol are used. p.34 [step 7 in for] "add" means "uses the predefined generic function +" p.35 [non-local exits] Clarify that "Normally..." means something like "In the absence of non-local exits..." What type of object is the exit procedure? It is a <function>. p. 35, 36 [block no semantics] There is no discussion of the semantics of interleaving cleanup and exception clauses. [Since the DIRM, the block form has been simplified and interleaving of cleanup and exception clauses is no longer allowed.] p.39... [Comparisons chapter] Should things like < and <= be defined as [Function] or [Operator]? Should they be defined as \<? It is unclear from the descriptions of >, <= and >= whether they are implemented with only < or with both < and =. They are implemented with only < right now, but IEEE might change that. Regarding == and builtin number classes: does this hold for floating point, double precision floating point, etc.? Definitely yes. pp.43-45 "A complete description of parameter lists and congruency is given in the Function Applicability section": There is no such section. p.44, 70 [implicit generic function signatures] When define method implicitly creates a generic function, it's not said how this default generic function's parameter list is computed. (It isn't the same as the method's parameter list.) The DIRM needs to specify how Dylan computes implicit generic function signatures. "parameters bound as lexicals over scope of body" might be thought to include result "parameters." Clarify. p.44 [method], 48 [parameter lists], and 53-54 [result values] These sections don't adequately explain the syntax of value declarations. In particular, they don't explain the necessity of parentheses around value declarations. The correct syntax is as defined in the BNF. p.47 [local] Is it possible to construct a local generic function by doing something like the following: local method double(x :: <number>) x + x end method double, method double(x :: <string>) concatenate(x, x) end method double; double p.49 [#all-keys] #all-keys should have a similar statement to #key that the parameter list could also specify #rest. It should specify more clearly here that if a function takes keyword parameters, taking a rest parameter still limits it to accepting only keyword/value pairs. What #all-keys means for generic functions should be stated here as well as on p.55. p. 51 [type specializers] "A specializer can be any expression...": This should note that syntax is limited; binary operators would have to be parenthesized. What is the scope/environment that types are evaluated in? is evaluation left to right? p. 52 [keyword default values syntax] The syntax for keyword default values changed after the DIRM went to press. The correct syntax uses '=' instead of parentheses: define method initialize (xyzzy :: <my-object>, #key size = 1); or ... , #key size: the-size = 1); p. 55 [Use = for keyword parameter defaults] Default values for keyword parameters are now specified with = (see proposal "Keyword default syntax," Keith Playford, May 18th) p. 56 [method specificity] What sort of error is "ambiguous method error"? Type equivalence should be defined. p. 61 [passing different arguments to next-method] This should make a note about the leftmost keywords being used where duplicates occur, so in order to replace a key/value pair, just prepend to the rest list. p. 62 [generic-function-methods] Is generic-function-methods allowed to return a collection instead of a sequence? add-method can signal a <sealed-object-error>. pp.65-66 [<function>, <generic-function>, and <method>] Shouldn't there be a values: init-keyword for <generic-function>? Did we forget to add that? If so, we also forgot to add a function-value-specializers function or an additional value from function-specializers or function-arguments. p. 67 [slots] "Slots are local storage within instances" is misleading, given other allocation types. "Local storage within instances or classes is in slots" might be better. p. 63 [function-arguments] Function-arguments returns the symbol #"all" (the existing text doesn't use symbol syntax) p.69 [defining new classes] "New classes are created with define class": New classes can also be created through make but this is not documented here. p.80 (second line) "...some keyword is neither usable for slot initialization nor recognized by some initialize method ..." The word 'recognized' should instead be the term 'permitted.' p.83 [Initialization Argument Inheritance] What is the default type if none is explicitly specified in the local specification? pp.83-84 [Initialization of Class Allocated Slots] Clarify that this refers to what the default make method does. p.84 [slot-initialized?] What does slot-initialized? do on a virtual slot? p.86 [class-for-copy] Clarify that class-for-copy can be extended for non-collection classes. p.87 [<class>] Should there be a default for superclasses:? There isn't one for define class. Do we need init-keywords for abstract: and primary:? What about initarg specifications? Inherited slot specifications? Chapter 8 [Controlling Dynamism] This chapter is far too terse! This chapter uses some undefined terms: explicitly defined explicitly known disjoint p.95 [Collections graphic] The graphic at the beginning of the chapter is inaccurate about which classes are abstract. Some classes, such as <string> are both abstract and instantiable. p.96 [size, etc] Is size required to terminate? Are any collection methods required to terminate? p.96 [mapping functions such as do and map, etc] The function parameters to the mapping functions should be listed as "function" instead of "procedure." Also clarify how many arguments the called function will receive. What should mapping functions do when the arguments are unbounded collections? Should functions which make no sense for unbounded collections have methods that explicitly signal errors? p. 98 [map-into example] The example on page 98 for 'map-into' is incorrect. The text on page 97 describes the correct behavior. map-into returns the mutable-collection argument, but 'procedure' is not applied to this argument as the example implies. p. 100 [skip parameter of find-key] The "skip" parameter of "find-key" is currently close to useless because the elements are not examined in a known order. For explicit key collections we can't assume any "natural order". pp.101-109 [Functions for Sequences] The "Collections" chapter probably needs to make stronger statements for many collection and sequence operations concerning the order in which collection elements are "processed" and the order in which elements will appear in the operation's result value. Why are add and remove guaranteed to copy (that is, the resultant sequence may share no structure with the original sequence)? concatenate is contradictory about whether a new sequence is created with make, or structure sharing is done. Does last signal an error if its argument sequence is unbounded? p.105 [remove duplicates does NOT remove first occurrence?] When "remove-duplicates" or "remove-duplicates!" finds duplicate elements, should it remove the first or later occurrences. The examples show that these routines remove later occurrences, but is this guaranteed behavior? p. 107 [replace-subsequence! overspecified] From the description of replace-subsequence!: result-sequence will not share structure with insert-sequence. The requirement, as it stands, means any method for two lists must scan the result to make sure no part of insert-sequence is part of the result. If there is incidental sharing, then the method must make new pairs and replace those shared pairs. This should probably be respecified, p.107, 108 [reverse! and sort!] The definitions of reverse! and sort! probably should be explicit that you should set something to the result (in order to avoid the usual screw). p.108 [first-, second-, and third-setter] The descriptions for first-, second-, and third-setter should have mutable-sequence instead of sequence. p.110 [<byte-string>] p.112 [<string>] What is the default for fill: in a <byte-string>? What is the default for fill: in a <string>? p.115 [deques] Should push, pop, and push-last be called push!, pop!, and push-last!? p.120 [< on strings] Omit "lexicographic" in the description of < on strings. p.122 [iteration protocol] "Use of the iteration protocol is based on the assumption..." if this assumption is violated, can it cause failures which cause the system to fail? That is, could it lead to a core dump? p.123 [iteration protocol] What should a class which cannot implement every piece of the iteration protocol do? This should be clarified. Is backward-iteration-protocol required to produce the items in reverse order from forward-iteration-protocol? It probably should be. p.129 [<explicit-key-collection>] p.131 [<mutable-explicit-key-collection>] The classes <explicit-key-collection> and <mutable-explicit-key-collection> aren't necessary any more with the new iteration protocol. They should probably go away. p.135 [<character>] p.136 [<symbol>] Are <character> and <symbol> really suitable arguments to make? Are they sealed classes? p.135 [as] Are the methods on as that convert between characters and integers required to be inverses of each other? p.137 [Numbers chapter] This chapter doesn't explain the syntax of numbers. The graphic at the beginning of the chapter is inaccurate about which classes are abstract and/or instantiable. Are all implementations required to support all three float formats? Is IEEE format really required? p.138 [numeric classes] There should be some text to describe these classes! The guaranteed precision of <integer> should be specified to be "at least 28 bits." p. 139 [/ undefined on integers] This page fails to note that / on integers is undefined. pp.139-141 [Arithmetic Operations] Are the type restrictions on the G.F.'s that are implied by these descriptions accurate? i.e, expt number1 integer2? Are logior, logxor, and logand really G.F.s? It's not true that rationalize is the same as Scheme, because the Scheme function of that name has two required arguments. p. 161 [do-handlers] The description of "do-handlers" says the "init-arguments" argument to funarg will be #f if unsupplied by the handler. The "init-arguments" argument actually defaults to an empty sequence. p. 163 [modules overview] Second paragraph of the "Overview" section: "Is an error" is too weak of a classification for importing or creating two variables with the same name in the same module. Third paragraph of the "Overview" section: "Owned variables are created by a create clause in a define module and in some cases by definitions associated with a module." The quoted expression could be misleading. It seems to some that it is more likely that a variable will be created by a definition rather than through the create option to "define module". p.171-173 [Libraries chapter] This chapter is far too terse. The Dylan module, Dylan-user module, and Dylan library should be mentioned at the beginning of the preceding modules chapter, and preferably earlier in the book as well, not snuck into the back of the libraries chapter. p.177 [BNF notation notes] The BNF needs to have a better description of its notation. Note: the notation is not really BNF. BNF is the name of a different notation. Note: The Annotated C++ Reference Manual, by Ellis and Stroustrup, uses the same notation (except without "...") The BNF does not list the definition of the non-terminals DEFINE-WORD, SIMPLE-BEGIN-WORD, EXPR-BEGIN-WORD, BEGIN-WORD, SIMPLE-INTERMEDIATE-WORD, EXPR-INTERMEDIATE-WORD, and INTERMEDIATE-WORD. They should be: simple-begin-word: one of begin case expr-begin-word: one of if unless until while begin-word: one of block for select simple-intermediate-word: one of cleanup else finally expr-intermediate-word: one of elseif intermediate-word: one of exception define-word: one of class constant library module variable The BNF does not support seal generic. The right solution is probably to choose a new syntax for it rather than to kludge up the grammar to support the existing syntax, since the existing syntax was only intended as a placeholder.